
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>

<HEAD>
   <TITLE>gfrepi_c</TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<A name="TOP"></A>

<table style="text-align: left; margin-left: auto; margin-right: auto; width: 800px;"
 border="0" cellpadding="5" cellspacing="2">
  <tbody>
    <tr>
      <td style="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
      <div align="right"> 
      <small><small><a href="index.html">Index Page</a></small></small>
      </div>
      <b>gfrepi_c</b> </td>
    </tr>

    <tr>
      <td style="vertical-align: top;">

<small><div align="center">
<A HREF="index.html#A">A</A>&nbsp;
<A HREF="index.html#B">B</A>&nbsp;
<A HREF="index.html#C">C</A>&nbsp;
<A HREF="index.html#D">D</A>&nbsp;
<A HREF="index.html#E">E</A>&nbsp;
<A HREF="index.html#F">F</A>&nbsp;
<A HREF="index.html#G">G</A>&nbsp;
<A HREF="index.html#H">H</A>&nbsp;
<A HREF="index.html#I">I</A>&nbsp;
<A HREF="index.html#J">J</A>&nbsp;
<A HREF="index.html#K">K</A>&nbsp;
<A HREF="index.html#L">L</A>&nbsp;
<A HREF="index.html#M">M</A>&nbsp;
<A HREF="index.html#N">N</A>&nbsp;
<A HREF="index.html#O">O</A>&nbsp;
<A HREF="index.html#P">P</A>&nbsp;
<A HREF="index.html#Q">Q</A>&nbsp;
<A HREF="index.html#R">R</A>&nbsp;
<A HREF="index.html#S">S</A>&nbsp;
<A HREF="index.html#T">T</A>&nbsp;
<A HREF="index.html#U">U</A>&nbsp;
<A HREF="index.html#V">V</A>&nbsp;
<A HREF="index.html#W">W</A>&nbsp;
<A HREF="index.html#X">X</A>&nbsp;
</div></small>
       <br>
       <table style="text-align: left; width: 60%; margin-left: auto; margin-right: auto;"
       border="0" cellspacing="2" cellpadding="2">
        <tbody>
          <tr>
            <td style="width: 50%; text-align: center;">
            <small>
              <a href="#Procedure">Procedure<br></a>
              <a href="#Abstract">Abstract<br></a>
              <a href="#Required_Reading">Required_Reading<br></a>
              <a href="#Keywords">Keywords<br></a>
              <a href="#Brief_I/O">Brief_I/O<br></a>
              <a href="#Detailed_Input">Detailed_Input<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Detailed_Output">Detailed_Output<br></a>
              <a href="#Parameters">Parameters<br></a>
              <a href="#Exceptions">Exceptions<br></a>
              <a href="#Files">Files<br></a>
              <a href="#Particulars">Particulars<br></a>
              <a href="#Examples">Examples<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Restrictions">Restrictions<br></a>
              <a href="#Literature_References">Literature_References<br></a>
              <a href="#Author_and_Institution">Author_and_Institution<br></a>
              <a href="#Version">Version<br></a>
              <a href="#Index_Entries">Index_Entries<br></a>
             </small>
            </td>
          </tr>
        </tbody>
</table>

<h4><a name="Procedure">Procedure</a></h4>
<PRE>
   void gfrepi_c ( SpiceCell        * window,
                   ConstSpiceChar   * begmss,
                   ConstSpiceChar   * endmss  ) 
 
</PRE>
<h4><a name="Abstract">Abstract</a></h4>
<PRE>
 
   This entry point initializes a search progress report. 
  </PRE>
<h4><a name="Required_Reading">Required_Reading</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Keywords">Keywords</a></h4>
<PRE>
 
   UTILITY 
 

</PRE>
<h4><a name="Brief_I/O">Brief_I/O</a></h4>
<PRE>
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   MXBEGM     P   Maximum progress report message prefix length. 
   MXENDM     P   Maximum progress report message suffix length. 
   window     I   A window over which a job is to be performed. 
   begmss     I   Beginning of the text portion of the output message. 
   endmss     I   End of the text portion of the output message. 
 </PRE>
<h4><a name="Detailed_Input">Detailed_Input</a></h4>
<PRE>
 
   window   is the name of a constraint window. This is the window 
            associated with some root finding activity. It is 
            used to determine how much total time is being searched 
            in order to find the events of interest. 

 
   begmss   is the beginning of the progress report message 
            written to standard output by the GF subsystem.
            This output message has the form 
 
               begmss xxx.xx% endmss 

            For example, the progress report message created
            by the CSPICE routine <a href="gfocce_c.html">gfocce_c</a> at the completion
            of a search is

               Occultation/transit search 100.00% done.

            In this message, begmss is

               &quot;Occultation/transit search&quot;

            The total length of `begmss' must be less than 
            MXBEGM characters.

            All characters of `begmss' must be printable.

 
   endmss   is the last portion of the output message 
            written to standard output by the GF subsystem.

            The total length of `endmss' must be less than 
            MXENDM characters.

            All characters of `endmss' must be printable.

 </PRE>
<h4><a name="Detailed_Output">Detailed_Output</a></h4>
<PRE>
 
  None.
 </PRE>
<h4><a name="Parameters">Parameters</a></h4>
<PRE>
   MXBEGM, 
   MXENDM    are, respectively, the maximum lengths of the progress 
             report message prefix and suffix. 

             Normally CSPICE developers will not need to reference
             these parameters; these are discussed only to help
             explain the functionality of this routine.

             The values of these parameters are defined in the
             SPICELIB Fortran INCLUDE file

                zzgf.inc
 </PRE>
<h4><a name="Exceptions">Exceptions</a></h4>
<PRE>
 
   1) If `begmss' has length greater than MXBEGM characters, or if 
      `endmss' has length greater than MXENDM characters, the error 
      SPICE(MESSAGETOOLONG) is signaled. 
 
   2) If either `begmss' or `endmss' contains non-printing characters, 
      the error SPICE(NOTPRINTABLECHARS) is signaled. 

   3) The error SPICE(EMPTYSTRING) is signaled if the either input
      string does not contain at least one character, since the
      input string cannot be converted to a Fortran-style string
      in this case.
      
   4) The error SPICE(NULLPOINTER) is signaled if either input string
      pointer is null.
</PRE>
<h4><a name="Files">Files</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Particulars">Particulars</a></h4>
<PRE>
  
   This is one of three GF progress reporting routines that cooperate
   in order to display a report via console I/O. These routines may 
   be used by SPICE-based applications as inputs to mid-level GF 
   search routines.
 
   Developers wishing to use their own GF progress reporting routines
   must design them with the same interfaces and should assign them the
   same progress reporting roles as those of these routines.

   The GF progress reporting API routines are written to simplify
   reporting of work (such as searching for a geometric event) over a
   particular window. This is an important feature for interactive
   programs that may &quot;go away&quot; from the user's control for a
   considerable length of time. It allows the user to see that
   something is still going on (although maybe not too quickly).
 
   The three routines constituting the GF progress reporting API
   are: 
 
      <b>gfrepi_c</b>  is used to prepare the reporting mechanism for a search
                pass. It is used to store the confinement window and
                progress report message prefix and suffix, and to
                initialize parameters associated with the reporting of
                the job in progress.
 
      <a href="gfrepu_c.html">gfrepu_c</a>  is used to notify the progress reporting system that
                a specified increment of work has been completed
                since the last call to <a href="gfrepu_c.html">gfrepu_c</a> or <b>gfrepi_c</b>, whichever
                occurred most recently.
 
      <a href="gfrepf_c.html">gfrepf_c</a>  is used to &quot;finish&quot; the reporting of work (set the
                completion value to 100%.
 
 </PRE>
<h4><a name="Examples">Examples</a></h4>
<PRE>
   

   1)  This example shows how to call a mid-level GF search API that 
       requires as input progress reporting routines. 
 
       If custom progress reporting routines are available, they 
       can replace <b>gfrepi_c</b>, <a href="gfrepu_c.html">gfrepu_c</a>, and <a href="gfrepf_c.html">gfrepf_c</a> in any GF API calls. 
 
       The code fragment below is from the first code example in the 
       header of 
 
          <a href="gfocce_c.html">gfocce_c</a>.c
 
       Only the portions of that program relevant to use of the 
       progress reporting routines are copied here.


          /.
          Select a twenty-second step. We'll ignore any occultations
          lasting less than 20 seconds.
          ./
          <a href="gfsstp_c.html">gfsstp_c</a> ( 20.0 );

          /.
          Perform the search.
          ./
          <a href="gfocce_c.html">gfocce_c</a> ( &quot;ANY&quot;,
                     &quot;MOON&quot;,     &quot;ellipsoid&quot;,  &quot;IAU_MOON&quot;,
                     &quot;SUN&quot;,      &quot;ellipsoid&quot;,  &quot;IAU_SUN&quot;,
                     &quot;LT&quot;,       &quot;EARTH&quot;,      CNVTOL,
                     <a href="gfstep_c.html">gfstep_c</a>,   <a href="gfrefn_c.html">gfrefn_c</a>,     rpt,
                     <b>gfrepi_c</b>,   <a href="gfrepu_c.html">gfrepu_c</a>,     <a href="gfrepf_c.html">gfrepf_c</a>,
                     bail,       <a href="gfbail_c.html">gfbail_c</a>,     &amp;cnfine,
                     &amp;result                              );
</PRE>
<h4><a name="Restrictions">Restrictions</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Literature_References">Literature_References</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Author_and_Institution">Author_and_Institution</a></h4>
<PRE>
 
   N.J. Bachman   (JPL)
   L.S. Elson     (JPL) 
   W.L. Taber     (JPL) 
   I.M. Underwood (JPL) 
   E.D. Wright    (JPL)  
 </PRE>
<h4><a name="Version">Version</a></h4>
<PRE>
 
   -CSPICE Version 1.0.0, 28-FEB-2009 (NJB) (LSE) (WLT) (IMU) (EDW)
</PRE>
<h4><a name="Index_Entries">Index_Entries</a></h4>
<PRE>
 
   GF initialize progress report
 </PRE>
<h4>Link to routine gfrepi_c source file <a href='../../../src/cspice/gfrepi_c.c'>gfrepi_c.c</a> </h4>

      </td>
    </tr>
  </tbody>
</table>

   <pre>Wed Jun  9 13:05:24 2010</pre>

</body>
</html>

